Why are APIs important?

Data is a hugely valuable asset to most organizations — it provides information to answer end users’ questions (e.g., should a doctor schedule additional laboratory tests for a patient based on a blood panel) or serves as the input/output to various organizational processes (e.g., basic accounting features such as encumbering funds requires data as input and output). Data is everywhere, from website and desktop applications and mobile applications to bots like Google Home and Amazon Alexa.

All organizations accumulate and store data but how do they unlock the power of their data and leverage it effectively when the data is spread throughout various IT systems? Application program interfaces, or APIs, are the most commonly used method for interacting with an organization’s data when data is spread through diverse IT systems. APIs are sets of definitions for building out and integrating software applications. In layman’s terms, APIs are the behind-the-scenes instructions that tell products and services what kinds of information they can exchange with one another, and how those exchanges take place.

Below, we’ve outlined five best practices to guide your API designs to boost user experience and maximize data delivery and process execution.

Best practice #1: always link to a business process

Architect your APIs to fulfill a specific business process or request. It’s easy to approach API design from the wrong angle — building the API based on the design of the back-end databases or legacy systems that are exposed, rather than the use case they fulfill. Just as each business process in an organization meets a certain need or goal, each API should achieve an end user goal as well.

Take the following example:

As part of new employee onboarding, your company has a business process in place to order a mobile phone for the new employee. You should develop an API to achieve the goal of that business process. The API should accept data elements that fit the specific context of ordering a mobile phone and avoid using secret codes as inputs that represent database fields that only the IT service desk team could understand. In this case, the API should accept “USA” or “CANADA” as a country instead of a “101” for USA and a “54” for Canada. In addition, the end user should not have to call multiple fine-grained APIs to achieve their desired end state, such as several data lookup services to fulfill the final API call to order the mobile phone.

Thoughtfully designed APIs that execute business processes are particularly important when an organization attempts to optimize or automate their business processes. Using the mobile phone order API example above, an organization looking to streamline and automate its onboarding process could build a self-service portal that allows enew employees to order a mobile phone and existing employees to order a replacement mobile phone. By linking the API to a business process, the organization can reuse the business process for new and existing employees and automate it by hooking up a self-service portal to the API, reducing the time IT service desk members spend on ordering mobile phones.

Best practice #2: don’t try to please everyone

The time-tested truth that you “can’t win them all” is absolutely relevant in API design. Great APIs are designed to be simple, flexible, and easily adopted throughout an organization; however, having the API adopted throughout an organization means that the API must evolve in order to support every stakeholders’ needs and constraints. APIs that are designed to take everyone into consideration will ultimately fail simply because of the large number of stakeholders who can’t align on data elements, structure, and priorities.

It’s perfectly reasonable to design an API for one internal department to optimize efficiency! Once the API serves that department, you can form additional partnerships throughout the organization to evolve the API and reap its benefits. With that in mind, leave the extraneous data elements and additional features out during the initial design of the API to allow future growth and customization. Remember, you can always add elements, but it is extremely difficult to remove them. A great API will help grow an ecosystem of partners who will use and continue to evolve the API in ways that are mutually beneficial to everyone.

Best practice #3: layer in API governance

Managing an API and the effect to end users can be challenging! Knowing that changes to API features are inevitable as more users begin to consume the API over time, make sure your organization proactively establishes an API governance program (e.g., processes and standards for security, publishing, versioning, and monitoring of APIs). Your API governance program should address the following perspectives:

• Versioning – how to create new and backward compatible APIs
• Standards – technical best practices such as URL patterns and naming conventions
• Access – establishing who can access the API
• Privacy – who owns the data and are there any legal policies surrounding it
• Service level agreements – monitor the quality, availability, and responsibilities that are agreed on between the API provider and the consumer
• Measurements – establish success criteria and collect metrics to analyze the API’s success

When developing an API, you should be prepared for future change and iteration. Constructing a strong API governance process from the initial design will ensure that business and technical strategies and requirements are met from the early versions of the API.

Best practice #4: write excellent error messages

Exception and error handling are a very important piece of the puzzle for any API but are frequently forgotten or added to an application just before go-live. Error messages help end users understand what went wrong during an API request and are a key element to creating excellent end user experience. During API design, devote the same time and attention to crafting proper exception and error handling as you would any other design element. Make sure exception and error handling are detailed, precise and let the user know the nature of the error so they can figure their way out of a jam.

Best practice #5: think about performance from the start

When an API is created, its purpose should be very well-defined (hopefully by a business process!) and the usage is typically limited to the initial stakeholder. But what about the possibility of expanding the volume of calls? Can the API scale? Seasoned API designers develop an API performance strategy from the very start to ensure future success. A solid API performance strategy should answer these questions:

• What are the desired response times, network latency, and throughput?
• Is the response time degrading over time?
• Is the response time worse in production than in pre-production?
• Is the API too chatty (should the API be changed to return all, some, or a range of results)?
• What is the size of the payload?

Answering each of these questions requires a different level of optimization work and performance testing including load, stress, and soak testing. It’s important to identify initial and future performance metrics as part of the initial API design to scale out the API to a larger audience in the future.

Conclusion

APIs are the glue that connect various forms of data that may be spread out throughout various disparate systems. Thoughtful API design will increase adoption and improve end user experience, and ultimately lead to success throughout the lifecycle of an API. Be sure to consider the above best practices to maximize your success as you design APIs for your organization.